%% $Id$

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentclass[english]{article}
\usepackage[latin1]{inputenc}
\usepackage{babel}
\usepackage{verbatim}

%% do we have the `hyperref package?
\IfFileExists{hyperref.sty}{
   \usepackage[bookmarksopen,bookmarksnumbered]{hyperref}
}{}

%% do we have the `fancyhdr' or `fancyheadings' package?
\IfFileExists{fancyhdr.sty}{
\usepackage[fancyhdr]{latex2man}
}{
\IfFileExists{fancyheadings.sty}{
\usepackage[fancy]{latex2man}
}{
\usepackage[nofancy]{latex2man}
\message{no fancyhdr or fancyheadings package present, discard it}
}}

%% do we have the `rcsinfo' package?
\IfFileExists{rcsinfo.sty}{
\usepackage[nofancy]{rcsinfo}
\rcsInfo $Id$
\setDate{\rcsInfoLongDate}
}{
\setDate{2018/07/05}
\message{package rcsinfo not present, discard it}
}

\setVersionWord{Version:}  %%% that's the default, no need to set it.
\setVersion{=PACKAGE_VERSION=}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}

\begin{Name}{1}{hpcstruct}{The HPCToolkit Performance Tools}{The HPCToolkit Performance Tools}{hpcstruct:\\ Recovery of Static Program Structure}

\Prog{hpcstruct} recovers the static program structure of \emph{fully optimized} object code for use with an \textbf{HPCToolkit} correlation tool.
In particular, \Prog{hpcstruct}, recovers source code procedures and loop nests, detects inlining, and associates procedures and loops with object code addresses.
See \HTMLhref{hpctoolkit.html}{\Cmd{hpctoolkit}{1}} for an overview of \textbf{HPCToolkit}.

\end{Name}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Synopsis}

\Prog{hpcstruct} \oOpt{options} \Arg{binary}

Typical usage:\\ \\
\SP\SP\SP\Prog{hpcstruct} \Arg{binary} \\ \\
which creates \File{basename(}\Arg{binary}\File{).hpcstruct}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Description}

Given an application binary or DSO \Arg{binary},
\Prog{hpcstruct} recovers the program structure of its object code.
Program structure is a mapping of a program's static source code structure to its object code.
By default, \Prog{hpcstruct} writes its results to the file \emph{basename(binary)}\File{.hpcstruct}.
This file is typically passed to \textbf{HPCToolkit}'s attribution tool \HTMLhref{hpcprof.html}{\Cmd{hpcprof}{1}}.

\Prog{hpcstruct} is designed to handle highly optimized binaries created from C, C++ and Fortran source code.
Because \Prog{hpcstruct}'s algorithms exploit a binary's debugging information,
\Arg{binary} should be compiled with options to produce as much debugging information as possible.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Arguments}

%% SKW 7/6/18:
%% 
%% The following arguments are implemented in hpcstruct's "Args.cpp" but are deprecated
%% and so not documented here, per JohnMC
%% 
%%    agent-c++
%%    agent-cilk
%%    loop-intvl
%%    loop-fwd-subst
%%    normalize
%%    use-binutils

\begin{Description}
\item[\Arg{binary}] File containing a binary executable or dynamically linked library.
Note that \Prog{hpcstruct} does not recover program structure for libraries that \Arg{binary} depends on.
To recover that structure, run hpcstruct on each dynamically linked library
or relink your program with static versions of the libraries.
\end{Description}

Default values for an option's optional arguments are shown in \{\}.

\subsection{Options: Informational}

\begin{Description}
\item[\OptoArg{-v}{n}, \OptoArg{--verbose}{n}]
Verbose: generate progress messages to stderr at verbosity level \Arg{n}.  \{1\}

\item[\Opt{-V}, \Opt{--version}]
Print version information.

\item[\Opt{-h}, \Opt{--help}]
Print help.

\item[\OptoArg{--debug}{n}]
Print debugging messages at debug level \Arg{n}. \{1\}

\item[\OptArg{--debug-proc}{glob}]
Print debugging messages for structure recovery of procedures matching the shell glob \Arg{glob}.
\end{Description}


\subsection{Options: Structure recovery}

\begin{Description}

\item[\OptArg{--demangle-library}{libpath}]
Use a function from the library at \emph{libpath} to demangle C++ names.
By default the library function used is \Prog{__cxa_demangle}.
A different function may be specified with the \Prog{--demangle-function} option.

\item[\OptArg{--demangle-function}{funcname}]
Call the function named \emph{funcname} in the specified demangler library to demangle C++ names.
This option may only be given if the \Prog{--demangle-library} option is also given.

\item[\OptArg{-I}{path}, \OptArg{--include}{path}] 
Use \Arg{path} when resolving source file names. 
This option is useful when a compiler records the same filename in different ways within the symbolic information.
(Yes, this does happen.)
For a recursive search, append a '+' after the last slash, e.g., \texttt{/mypath/+}. 
This option may appear multiple times.

\item[\OptArg{-R}{'old-path=new-path'}, \OptArg{--replace-path}{'old-path=new-path'}]
Replace instances of \Arg{old-path} with \Arg{new-path} in all paths with \Arg{old-path} is a prefix
(e.g., a profile's load map and source code).
Use \verb+'\'+ to escape instances of '=' within specified paths.
This option may appear multiple times.
  
Use this when a profile or executable references files that have been relocated,
such as might occur with a file system change.

\end{Description}


\subsection{Options: Output}

\begin{Description}

\item[\OptArg{-o}{file}, \OptArg{--output}{file}]
Write results to \Arg{file}.  Use '-' for \File{stdout}. \{\Arg{basename(binary)}\File{.hpcstruct}\}

\item[\Opt{--compact}]
Generate compact output by eliminating extra white space.

\item[\Opt{--show-gaps}]
Write a text file describing all the "gaps" found by \Prog{hpcstruct},
i.e. address regions not identified as belonging to a code or data segment
by the ParseAPI parser used to analyze application executables.
The file is named \emph{outfile}\File{.gaps}, which by default is \emph{appname}\File{.hpcstruct.gaps}.
A gaps file can't be written when \emph{outfile} is \Prog{stdout}.


\end{Description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Examples}

%\begin{enumerate}
%\item 
Assume we have collected profiling information for the (optimized) binary \File{sweep3dsingle},
compiled with debugging information.
We wish to recover program structure in the file \File{sweep3dsingle.hpcstruct}
for use with \HTMLhref{hpcprof.html}{\Cmd{hpcprof}{1}}.
To do this, execute:

\begin{verbatim}
    hpcstruct sweep3dsingle
\end{verbatim}

By defult the output is placed in a file named \File{sweep3dsingle.hpcstruct}.
%\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Notes}

\begin{enumerate}

\item For best results, an application binary should be compiled with debugging information.
To generate debugging information while also enabling optimizations,
use the appropriate variant of \verb+-g+ for the following compilers:
\begin{itemize}
\item GNU compilers: \verb+-g+
\item Intel compilers: \verb+-g -debug inline_debug_info+
\item IBM compilers: \verb+-g -fstandalone-debug -qfulldebug -qfullpath+
\item PGI compilers: \verb+-gopt+
\end{itemize}

\item While \Prog{hpcstruct} attempts to guard against inaccurate debugging information,
some compilers (notably PGI's) often generate invalid and inconsistent debugging information.
Garbage in; garbage out.

\item C++ mangling is compiler specific. On non-GNU platforms, \Prog{hpcstruct}
tries both platform's and GNU's demangler.

\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% \section{Bugs}
%% 
%% \begin{enumerate}

%% \item xxxxxx

%% \end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{See Also}

\HTMLhref{hpctoolkit.html}{\Cmd{hpctoolkit}{1}}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Version}

Version: \Version

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{License and Copyright}

\begin{description}
\item[Copyright] \copyright\ 2002-2019, Rice University.
\item[License] See \File{README.License}.
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Authors}

\noindent
Rice University's HPCToolkit Research Group \\
Email: \Email{hpctoolkit-forum =at= rice.edu} \\
WWW: \URL{http://hpctoolkit.org}.

Thanks to Gabriel Marin and Jason Eckhardt.

\LatexManEnd

\end{document}

%% Local Variables:
%% eval: (add-hook 'write-file-hooks 'time-stamp)
%% time-stamp-start: "setDate{ "
%% time-stamp-format: "%:y/%02m/%02d"
%% time-stamp-end: "}\n"
%% time-stamp-line-limit: 50
%% End:

